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Preface 

The H P-UX TN3270 Administrators Guide describes how to install, 
configure, and manageTN3270. 


Intended Audience 


This book is intended for administrators responsible for installing, 
configuring, using, and maintainingTN3270 on a computer that uses the 
HP-UX operatingsystem. 
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About This Book 


This section explains how informatoin is organized and presented in this 
book. 

Organization of This Book 

This book is organized as follows: 

Chapter 1, "UnderstandingTN3270." 

Provides conceptual information to help you 
understand how to configure and manageTN 3270 and 
lists the administration tasks you need to perform 

Chapter 2, "I nstallingTN3270." 

Lists the hardware and software requirements, 
describes the installation process, and provides some 
guidelines for tuning after installation 

Chapter 3, “ConfiguringTN3270." 

Explains how toset up theTN3270 configuration file 

Chapter 4, "UsingTN3270 Log Messages." 

Describes events that TN3270 logs, the format of log 
messages, how to maintain log files, and how to 
interpret log messages 

Chapter 5, "UsingTN3270Tracing Facilities." 

Describes how totrace H LLAPI applications and the 
TN 3270 program, how to control the amount of trace 
data generated, and the format of the trace file 

Appendix A, "Required and Recommended Functions in theterminfo 
Database." 

Describes the recommended and required H P-UX 
terminal functions when using theTN3270 program 

Appendix C, "Mi grating from Earlier Versions of TN 3270." 

Describes how to mi grate from TN3270 Release 4 to 
Release 5 and Release 5 to Release 6 


9 




Table 1 


Typographic Conventions 

Table 1, "Typographic Conventions,"shows the typographic styles used 
in this document. 

Typographic Conventions 


Special Element 

Sample of Typography 

Document title 

HP-UX SNAplus2 3270 & TN3270 
HLLAPI Programmers Guide 

File or path name 

com.cfg 

Directory name 

/opt/sna/ 

Program or application 

tncfgtcp 

Command or HP-UX utility 

vi 

Option or flag 

TRON 

Parameter 

tn3270_support 

Name of a TN3270 
configuration record 

host record 

Constant 

IBM-DYNAMIC 

Return value 

System limit 

Variable representing a 
supplied value 

devicename 

Environment variable 

PATH 

User input 

filel.trc : file2.trc 

Computer output 

3270 Message 0-26, Subcode:0 

Descriptive phrase about a 

1 i ne of code 

12:17:28 GMT 11 Nov 1996 

Timestamp 

Function 

Set Session Parameters 

Hexadecimal value 

0x20 

3270 key 

ENTER 
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Table 1 Typographic Conventions 


Special Element 

Sample of Typography 

Keyboard keys 

Up 
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TN3270 Manual Set 

TheTN 3270 product provides the following documentation: 

HP-UX TN3270 Administrators Guide 

Explains how to install, configure, and manage 
TN3270. It describes the requirements for installing 
theTN3270 software, how to set up configuration 
information for using 3270 emulation, and how to use 
the product's diagnostics tools to resolve problems. 

HP-UX TN3270 Users Guide 

Explains how to use 3270 emulation, including the 
following tasks: 

• Start and stop 3270 emulation. 

• Transfer files. 

• Use customization features such as remapping your 
keyboard and display colors. 

• Interpret status-line information. 

• View response times. 

HP-UX SNAplus2 3270 & TN3270 H LLAPI Programmers Guide 

Contains the conceptual and detailed reference 
information needed to write application programs 
using high-level language application program 
interface (H LLAPI). 
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Related Publications 

For additional information about IBM 3270 Information Display System 
Products, refer to the foil owing publications: 

• IBM 3270 I nformation Display System: 

— 3274 Control Unit Description and Programmer's Guide, 
GA23-0061 

— Color and Programmed Symbols, GA33-3056 

— 3274 Control Unit Display Station: Operator's Guide, GA23-0023 

— 3174 Control Unit Functional Description, GA23-0218 

• The following Internet Requests for Comments (RFCs): 

— 854: Telnet Protocol Specification 

— 855: Telnet Option Specifications 

— 856: Telnet Binary Transmission 

— 860: Tel net Timing Mark Option 

— 885: Telnet End of Record Option 

— 1041: Tel net 3270 Regi me 

— 1091: Tel net Terminal Type Option 

— 1123: Requirements for I nternet Hosts—Application and Support 

— 1576: TN3270 Current Practices 

— 1646: TN3270 Extensions for Lunameand Printer Selection 

— 1647: TN3270 Enhancements 
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Understanding TN3270 


Chapter 1 
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Understanding TN3270 

Overview 


Overview 

This chapter provides an overview of theTN 3270 product and describes 
the responsibilities of theTN3270 administrator. The administrator is 
responsible for installing, configuring, and managing the TN 3270 
software. 


16 


Chapter 1 




Understanding TN3270 

What Is TN3270? 


What ISTN3270? 

TN3270 is a software product that enables H P-UX computer terminals to 
connect over a TCP/I P network and emulate 3270 terminals connected to 
a host computer. Two versions of the TN 3270 program, with different 
user interfaces, are available: a character-based version that runs on 
standard text terminals and a Motif graphical user interface. 

The TN 3270 program can connect directly to a host computer that 
supports TN 3270 access over TCP/I P or to a communications product 
that provides theTN Server function. The standard SNAplus2 product 
provides theTN Server function; therefore, theTN3270 programs can 
access a host over the SNA communications links provided by SNAplus2. 

You can configure theTN 3270 program to grant different user 
permissions for the foil owing options: 

• Controlling TN3270 sessions 

• Customizing TN3270 emulation features such as key mappings and 
display attributes 

• Transferring files between the local and host computers 

• Viewing a chart of host response times 

• Running HLLAPI applications 

Each user's copy of theTN 3270 program can access up to ten TN3270 
sessions to the same host or to different hosts. 

For information about using theTN 3270 software, refer to the FI P-UX 
TN3270 Users Guide 

TN3270 Features 

TN3270 provides the foil owing additional features: 

FI LLAPI support 

The high level language application program interface 
(FI LLAPI) enables you to develop application programs 
that communicate with theTN 3270 program to 
perform tasks, such as entering data and searching the 
screen for specific messages, that are normally done by 
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aTN3270 user. Using this API enables you toautomate 
frequently used TN3270 emulation tasks, such as host 
application startup. 

For more information about the functions provided by 
HLLAPI, refer to the HP-UX SNAplus2 3270 & 
TN3270 HLLAPI Programmers Guide 

TN 3270 style files 

The TN 3270 program enables you to customize 
TN 3270 emulation parameters such as color mappings, 
H P-UX terminal keys used to represent host 3270 keys, 
and HLLAPI session IDsfor TN3270 sessions. The 
details of this customization are stored in a style file 
that is loaded when the TN 3270 program is started. 
You can set up a standard style for all your TN3270 
users, or you can allow users to customize these 
settings individually and createtheir own stylefiles. 

Configuration file 

A single configuration file contains the foil owing details 
of your TN3270 configuration: 

• H ost computers you want to access 

• TN3270 emulation functions availableto individual 
TN 3270 users 

• F i I es used to record TN 3270 di agnosti cs 
information 

You can create and modify the configuration file as a 
simple text file using any standard ASCI I text editor, 
such as vi. The TN 3270 tncfgtcp program validates 
the configuration and generates a binary configuration 
file for use by TN 3270 components. 

Diagnostics support 

The following log and trace files can help you diagnose 
TN3270 errors, events, and system problems: 

Error log file 

A single file that contains a record of any errors that 
TN3270 detects. The name of this file is specified in the 
configuration file. 
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Audit log file 

A single file that contains a record of all significant 
system events. The name of this file, and the level of 
detail recorded in it, are specified in the configuration 
file. 

Trace files 

One or more optional trace files record the data 
transferred between theTN 3270 program and the host, 
or between a HLLAPI application andtheTN3270 
program. You can use these files to help you debug 
specific problems. Tracing is normally disabled because 
it degrades system performance. 

All these files aresimpletext files; you can view them 
with any ASCI I text editor, such as vi. 

TN3270 Features Supported 

The TN 3270 product supports both the standard TN 3270 features and 
the extended TN3270E features that are described in the Internet RFCs 
listed in "Related Publications". TN3270E supports all the standard 
TN3270 features and the foil owing additional features: 

• LU type 1 and LU type 3 printing 

• Access to specific display and printer LUs 

• Access to printer LUs associated with display LUs 

• Access to the SSCP-LU session 

• Support for the ATTN and SYSREQ keys 

• Negotiation of which enhancements to use on each connection 

TheTN3270E features are supported only if the directly connected host, 
or the communications product that provides theTN Server function, 
also supports theTN 3270E features. When the connection is established, 
the host or communications product negotiates with theTN3270 product 
to determi ne the level of support. 

You can configure the level of support that you desire for theTN 3270 
product by specifying a value for the tn3270_support field in the host 
record. You can determine the level of support that was negotiated by 
looking at the Control Display Sessions dialog box or the Control Printer 
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Sessions dialog box. For more information about these dialog boxes, refer 

totheTN3270 Users Guide. 

TN3270 does not provide support for the following functions that are 

described in the various RFCs that aresupported: 

• The device type ibm-dynamic. The device type that corresponds to 
the configured display model is used instead. 

• Keep-alive messages, although it does respond to them. If a TCP/I P 
connection is lost, the loss is detected when the user presses a key 
that causes data to be sent to the host. 

• TheSYSREQ key on non-TN3270E connections. 

• Renegotiation of device type, LU, orTN3270E functions on a 
connection that is already open. 
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What Are theTN3270 Administrator 
Responsi bilities? 

AstheTN3270 administrator, you have the foil owing responsibilities: 

1. I nstalling theTN3270 software. 

For more information about the hardware and software requirements 
for TN3270 and about installing the software, see Chapter 2, 

"I nstal I ingTN 3270." 

For additional information about install ingTN 3270, see Appendix A, 
"Required and Recommended Functions in theterminfo Database." 

If you have a previous version of TN3270 installed and are upgrading 
to this version, seeAppendix C, "Migrating from Earlier Versions of 
TN3270." 

2. Creating theTN3270 configuration file. This file describes the host 
TN 3270 facilities available, the TN 3270 users on your system and the 
facilities avail able to them, and the files used to store diagnostic 
information. 

For more information about creating theTN3270 configuration file, 
see Chapter 3, "ConfiguringTN3270." 

3. Setting up standard TN 3270 style files, if necessary. 

Refer tothe Fi P-UX TN3270 Users Guidefor information about 
creating, modifying, and saving style files. 

4. Monitoring and troubleshooting any problems that may arise during 
TN3270 operation. 

For more information about monitoring the TN 3270 error and audit 
log files and understanding their contents, see Chapter 4, "Using 
TN3270 Log Messages." 

5. UsingTN3270 facilities, if necessary, to diagnose specific problems. 

For information about control I ingTN 3270 tracing facilities and 
interpreting the generated trace files, see Chapter 5, "U si ngTN 3270 
Tracing Facilities." 
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Installing TN3270 

Overview 


Overview 

This chapter desribes the installation procedure used to install the 
TN3270 software. 
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Loading the Product Files 

After determining that you have the hardware, software and host 
requirements for theTN3270 product, you will need to load theTN3270 
product file, as follows: 

Step 1. E nsure that you have a CD-ROM drive attached to your system to read 
the product file. This drive should be configured on your system with an 
entry in the /dev directory. 

Step 2. Usethe H P-UX tool swinstaii to load theTN3270 product (load 

J 2636BA for Series 800 Systems or J 2637BA for Series 700 Systems). 
Refer to the man pages of the H P-UX system for instructions on how to 
do this. 

Step 3. Once you have loaded theTN 3270 product file, you can use the swverify 
command to: 

• verify whether TN3270 is compatible with the hosts on which the 
software was installed 

• verify that all dependencies (prerequisites) are being met for installed 
software 

• report missing files and check all file attributes including 
permissions, files types, siz, checksum, mtime, link source and other 
major/mi nor attributes. 

The command syntax for swverify is: 

swverify [-f file] [-s source] [-t target] 

Only use the swverify command through the command line interface. 
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Configuring TN3270 

Overview 


Overview 

This chapter describes how to configureTN 3270 and the information you 
need. 
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Overview of the Configuration Process 


Overview of the Configuration Process 

TN3270 uses a singleconfiguration file to hold the following details of 
your TN3270 configuration: 

• The host computers you can access 

• TheTN3270 emulation functions availableto individual TN3270 
users 

• The files used to record TN3270 diagnostics information 

You create this single binary configuration file by first defining a 
configuration text file and then using the tncfgtcp program to convert 
the text file to a binary file. 

Creating a Configuration Text File 

The configuration process begins with a simpletext filethat containsthe 
configuration information. A sample configuration text file, 
tnsampie.txt, is included with TN3270. Thesamplefile is located in 
subdirectory /opt/tn3270/sampies. You can use any standard ASCI I 
text editor (for example, vi) to modify a copy of the sample file to include 
the information you need or to create a new configuration file. 

When you have created the configuration text file, name it 
/opt/tn3270/sampies/com. txt. For more information about the 
configuration text file, see "Understanding the Configuration Text File 
Records". 

Creating a Binary Configuration File 

TN3270 uses the configuration text fileas input to the tncfgtcp 
program, which validates the configuration and generates a binary 
configuration filefor use by TN3270 components. Following is the syntax 
of the tncfgtcp program: 

tncfgtcp filename .txt 

The name of thetext fileto be converted to binary is filename, txt. This 
file name must have the extension .txt. I ndude the directory path if the 
file is not in the current directory. 

If the tncfgtcp program detects an error, such as an invalid file name or 
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a syntax error i n the text file, it writes a message to standard error and 
does not create a binary configuration file. For syntax errors, the 
program continues to parse the text file and writes a separate message 
for each error it finds. Correct the errors and run tncfgtcp again. 

If no errors are found, TN3270 creates the binary configuration file in the 
same directory as the text file. The binary configuration file has the same 
name as the text file but with the extension . cfg instead of .txt. 

Specifying the Path for the tncfgtcp Program 

The tncfgtcp program is stored with all other executable programs in a 
directory specific to TN 3270, /opt/tn3270/bin. Specify the path to this 
directory in one of the following ways: 

• Add the directory to your path environment variable in your .login 
or .profile file before initially running the programs. 

• I ncl ude the di rectory name each ti me you run the programs, as 
follows: 

/opt/tn3270/bin/tncfgtcp newfile.txt 


NOTE The sample command lines shown in this guide assume that you have 

added the directory to your path environment variable. Therefore, they 
do not i ncl ude the di rectory name. 


Creating Multiple Configuration Files 

When a user starts the TN 3270 program, TN3270 obtains its 
configuration information fromthefile /etc/opt/tn3270/com.cfg. This 
file is known as the running configuration file.. 

You can create several different TN 3270 configurations and save them in 
different configuration files. To use a particular configuration, copy its 
binary configuration fileto com.cfg in the appropriate subdirectory. Also 
copy the text configuration fileto com. txt in the same subdirectory so 
that you can easily check details of the current configuration. 

It is possible to write a new configuration directly to the running 
configuration file /etc/opt/tn3270/com.cfg by using the file 
/etc/opt/tn3270/com. txt as input. However, any active copies of the 


30 


Chapter 3 




Configuring TN3270 

Overview of the Configuration Process 


TN3270 emulation program continue to run with the previous 
configuration and are not affected by the change. For example, if you 
change the parameters that control whether audit or exception messages 
(or both) are recorded, any activeTN3270 emulation programs continue 
to use the previous settings. Users must stop and restart the TN 3270 
emulation program for the new settings to take effect. 
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Understanding the Configuration Text File 
Records 

The configuration text file contains the foil owing types of configuration 
records: 

host record 


Specifies the following information about a host that 
can be accessed usingTN3270: 

• Either the host's symbolic domain name or Internet 
Protocol (I P) 32-bit dotted-decimal address 

• TCP/IP port used to access the host 

• 3270 screen model that the host supports 

The configuration file contains at least one host record 
for each host that you can access. If a host can support 
more than one screen model, the configuration file has 
multiple host records for that host (one record for each 
screen model supported). 

The host record may correspond either to a host 
computer that supports di red TN 3270 access over 
TCP/I P or to another computer's communications 
produd that provides theTN Server fundion. The 
standard SNAplus2 produd provides TN Server 
fundion, which provides an intermediary fundion that 
conneds to terminals over TCP/I P and to the host over 
SNA communications links. 


user record 


Specifies the following information about aTN3270 
user: 

• User's H P-UX login name 

• User's default TN3270 stylefile 

• Hosts (identified by the name field of host records) 
that the user can use 

The configuration filecontains oneuser record for each 
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Example 3-1 

[record_name] 
field_name 


field_name 


H P-UX user who has permission to useTN 3270 
emulation. I nstead of configuring each user explicitly, 
you can set up a default user record to be used by any 
HP-UX user. 

diagnostics Record 

Specifies the following information about diagnostics: 

• Files used to hold TN3270 audit and error log 
information 

• Types of information logged 

• Boundaries used to classify Response Time Monitor 
(RTM) information 

The configuration file must contain one and only one 
diagnostics record, which may contain only the 
record header [diagnostics] or the record header and 
values. If only the [diagnostics] record header is 
present, default values for the fields are used. 

General Record Format 

The specific formats for host, user, and diagnostics records are 
described in the foil owing sections. Each record has the foil owing general 
format: 

General Record Format 


= value 


= value 

Each record_name or fieid_name entry must be on a separate line. The 
record_name must be in square brackets and must have a value of host, 
user, or diagnostics. Each record consists of one or morefield names 
and the values assigned to the field names. Valid field names for each 
record type are described in the section that describes that record. The 
allowed values for each field name depend on which of the following field 
types are described by the field name: 

record 
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A name that identifies the individual record. The value 
assigned must not match the name of any other record 
of the same type. The following characters are valid: 
A-Z, 0-9, @ #, and $. (The characters a-z are also 
accepted but are converted to uppercase.) 

The val ue chosen is for the System Admi nistrator's use 
only; it has no relevance outside of theTN 3270 system. 
Choose a name that identifies the resource. 


text 

Text string of any printable characters. The string is 
case sensitive and is not converted to uppercase. 

file 


H P-UX file name, which can be the file name only or 
can include a full path (do not use a relative path). 
Ensure that the file name and path are valid; TN3270 
does not check for validity of path and file name. 

number 


A numeric value interpreted as one of the foil owing: 

• Decimal by default 

• H exadeci mal if the val ue begi ns with "Ox" 

• Octal if the value contains a leading 0 (zero) 
character 


flag 

No value is assigned to a flag field. The inclusion of a 
flag field in a record implies that the option described 
by the flag is allowed. If the flag field is not included in 
a record, the corresponding option is not allowed. 

choice 


A choice among a group of values. The valid values are 
specified i n the notes for the field. 

The sections that follow describe the specific record formats for host, 
user, and diagnostics records. A table shows the fol lowi ng field 
attributes for each record type: 

• Which field type is expected for the field name. 


34 


Chapter 3 




Configuring TN3270 

Understanding the Configuration Text File Records 


• Range of allowed values. The value shown in the table depends on the 
field type: 

— For record, text, and file fields, range indicates the minimum and 
maximum number of characters allowed in a string. 

— For number fields, range indicates the minimum and maximum 
numeric values for the field. 

— For flag and choice fields, range is not used. 

• Whether the field is required or optional. 

• The default val ue used for any optional (non-flag) fields that do not 
have a value specified. No value, default or specified, is used for flag 
fields. 

Note also the foil owing conditions about the configuration text file: 

Order of Records and Fields 

I n general, the host, user, and diagnostics records 
within a configuration file can appear in any order. 
Similarly, the individual fields within a record can bein 
any order. However, the following restrictions apply: 

• A host record must be defined before any user 
record that refers to it. 

• A TN3270 user's sessions are assigned to the host 
fields in a user record in the order in which host 
records appear in the configuration file. For 
example, if you configure two host fields, the user's 
first session is assigned to the host described by the 
first host field, and the user's second session is 
assigned to the host described by the second host 
field. 

Blank space 

Field values cannot contain blank spaces; each value is 
a single continuous text string. All other blank spaces 
in the text file are ignored. Thus, any combination of 
spaces and tabs or completely blank lines is ignored. 

Comments 
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The semi-colon (;) character indicates a comment 
string. If you include this character at any point on a 
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Table 3-1 


line, any text following it (to the end of the line) is 
treated as a comment and ignored. 

Format of a host Record 

The host record provides information about a session with a TCP/I P 
host .Table 3-1, "Summary of host Parameters," summarizes the 
parameters in a host record. 


Summary of host Parameters 


Field name 

Type 

Range 

Req/Opt 

Default 

name 

record 

1-8 characters 

Required 

- 

domain 

text 

1-100 

characters 

Required 

- 

model 

choice 

- 

Optional 

2 

override 

flag 

- 

Optional 

- 

port 

numbe 

r 

1-65535 

Optional 

23 

tn3270_suppor 
t 

choice 

- 

Optional 

TN3270E 

lu_name 

record 

1-8 characters 

Optional 

- 

printer_name 

record 

1-8 characters 

Optional 

- 


Specify values for name, domain, and any desired optional fields as 
described in the following list: 


name 

Specify the name of theTN 3270 host record. Use 1-8 
characters from the foil owing set: A-Z, a-z, 0-9, @ # 
and $ (characters a-z are converted to uppercase). 

The val ue chosen is for the System Admi nistrator's use 
only; it has no relevance outside of the TN 3270 system. 
Choose a name that identifies the resource. 

domain 
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Specify either the symbolic domain name or the 32-bit 
dotted-decimal I nternet Protocol (IP) address of the 
TN3270 host. Use 1-100 of any printable, 
case-sensitive characters. For examples, see "Example 
of a host Record Using a Symbolic Domain Name" and 
"Exampleof a host Record Using a 32-Bit 
Dotted-Decimal IP Address". 

The host record may correspond to either of the 
following: 

• A host computer that supports di red TN 3270 access 
over TCP/I P. 

• Another computer's communi cati ons produd that 
provides the TN Server fundion. The standard 
SNAplus2 produd provides TN Server fundion. 
TheTN Server fundion provides an intermediary 
fundion that connedstoterminals overTCP/l P and 
to the host over SNA communications links. 


model 


Specify one of the foil owing values: 

2 

This session with a TN3270 host uses a 3270 screen 
model 2. 

3 

This session with a TN3270 host uses a 3270 screen 
model 3. 

4 

This session with a TN3270 host uses a 3270 screen 
model 4. 

5 

This session with a TN3270 host uses a 3270 screen 
model 5. 

PRINTER 

This session with aTN3270E host uses a printer. 


override 
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I nclude this field with no value if a TN3270 user can 
override the screen model (can change the TN 3270 
session customization to use a different model). 


port 

Specify the TCP/I P port number that the host uses for 
TN3270 data. 

tn3270_support 

Specify the level of TN3270 support desired. Possible 
values are: 

TN3270 

Only basicTN3270 protocols aresupported. Even if the 
host supportsTN3270E protocols, onlyTN3270 
protocols will be used on the session. 

TN3270E 

Both basic TN 3270 protocols and enhanced TN3270E 
protocols are supported. However, if the host does not 
support TN3270E, only TN3270 protocols will be used 
on the session. 

lu_name 

Specify the name of a specific display or printer LU. If 
this field is blank, a generic display or printer LU is 
used. 

printer_name 

Specify the name of a printer session associated with a 
display session. This field is ignored if the value of the 
tn3270_support field is TN3270 or if the value of the 
tn3270_support field is TN3270E and the value of the 
model field is printer. I f this field is blank, the 
display session has no associated printer session. The 
default value is blank. 

Following are two examples of host records: 

Example of a host Record Using a Symbolic Domain Name 


= hostrecl 
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domain 

= remote.host.addr 


model 

= 4 

; model 4: 43x80 

override 


; user can override screen model 

lu_name 

= TNLU1 

; use LU specified 

tn3270_support 

protocols 

= TN3270E 

; use enhanced TN3270E 


Example 3-3 

Example of a host Record Using a 32-Bit Dotted-Decimal IP 


Address 


[host] 

name 

= hostrec2 


domain 

= 123.123.123.123 


model 

= 4 

; model 4: 43 x 80 

override 


; user can override screen model 

port 

= 3270 


tn3270_support 

= TN3270E 

; use enhanced TN3270E protocols 


Format of user Record 

The user record specifies the details of a TN3270 user. Table 3-2, 
"Summary of Parameters," summarizes the parameters in a user record. 

Table 3-2 Summary of Parameters 


Fieldname 

Type 

Range 

Req/Opt 

Default 

name 

text 

1-20 

characters 

Required 

- 

host 

record 

1-8 

characters 

Optional 

See field 
description 

style_file 

text 

1-8 

characters 

Optional 

See field 
description 

modify_style 

flag 

- 

Optional 

- 

view_rtm 

flag 

- 

Optional 

- 

change_domain 

flag 

- 

Optional 

- 

Specify values for 
the foil owing list: 

name and any desired optional fields as described in 


Chapter 3 


39 



Configuring TN3270 

Understanding the Configuration Text File Records 


name 


Specify the name of theTN 3270 user. Use 1-20 of any 
pri ntable, case-sensitive characters. This val ue must 
match the HP-UX login ID of a user on the TN 3270 
computer. 

You can also set up a default TN 3270 user record, using 
the name <default> (in uppercase letters and 
surrounded by angle brackets, as shown). The 
<default> record allows any H P-UX user to use 
TN3270 emulation. If the user's H P-UX login ID does 
not match the name field in any user record, TN3270 
uses the <default> configuration record when the user 
starts TN 3270 emulation. 


host 


Specify the name of the host record that describes the 
session to be used. Use 1-8 characters from the 
following set: A-Z, a-z, 0-9, @ #and $ (characters a-z 
are converted to uppercase). This name must match 
the name of a host record in this configuration file. 

Specify a separate host field for each session that the 
user can access (maximum of 10 sessions). 

If you do not configure at least one host field, the user 
will not beabletousetheTN3270emulation program. 


style_file 

Specify the name of the default TN3270 style file for 
this user. Use 1-8 of any printable, case-sensitive 
characters. This style file is used if the TN 3270 user 
does not specify a style file when starting the TN 3270 
emulation program. 

If no file name is specified, theTN3270 emulation 
program uses its own default settings. 

Do not include an extension for the file name specified 
for this field becauseTN3270 adds the extension 
automatically. For example, if you enter the name 
newsty, TN 3270 uses the file newsty. stu. 

TN3270 searches for this file in the directory 
/etc/opt/tn3270. However, if you give the user 
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permission to modify the default style by including the 
modify_styie field, TN 3270 first searches for a file of 
the same name i n the user's home di rectory. I f you are 
setting up a standard style for all your users, store the 
file in /etc/opt/tn3270 and do not give users write 
access to this file. If you give a user permission to 
modify the default style, the user should save the 
modified version in the user's home directory with the 
same file name as the file in /etc/opt/tn3270. This 
ensures that the correct file is found when the TN 3270 
emulation program is started. 


modify_style 

I ncl ude this field with no val ue to give the TN 3270 user 
permission tochangetheTN3270customization (either 
by using theTN3270emulation program's menu 
interface or by loading a different style file). 


view_rtm 

I ncl ude this field with novaluetogivetheTN3270 user 
permission to view Response Time Monitor (RTM) data 
of host response times on each TN3270 session. To 
configure the boundaries by which responsetimes are 
classified, see "Format of user Record". 


Example 3-4 

[user] 

name 

host 

host 

host 

style_file 


change_domain 

I ncl ude this field with novaluetogivetheTN3270 user 
permission to specify an alternative domain and port 
for a particular session. For more information about 
host domains and ports, refer to the TN 3270 Users 
Guide. 

In the foil owing example, the user has three sessions: two sessions that 
use hostreci and one session that uses hostrec2: 

Example of a user Record 

= <DEFAULT> 

= hostreci 
= hostreci 
= hostrec2 

= stdsty ; this is /etc/opt/tn3270/stdsty.stu 

; modify_style not set - users can't use own style file 
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view_rtm 

change_domain 

records 


Table 3-3 


Fieldname 

Type 

Range 

Req/Opt 

Default 

error_file 

file 

5-49 

characters 

Optional 

/var/opt/tn327 0 
/sna.err 

audit_file 

file 

5-49 

characters 

Optional 

/var/opt/tn327 0 
/sna.aud 

audit 

flag 

- 

Optional 

- 

exception 

flag 

- 

Optional 

- 

rtm_bdy_l 

number 

5-1000 

Optional 

5 

rtm_bdy_2 

number 

5-1000 

Optional 

10 

rtm_bdy_3 

number 

5-1000 

Optional 

20 

rtm_bdy_4 

number 

5-1000 

Optional 

50 


; users can view RTM data 

; users can override domain and port field in host 


Format of diagnostics Record 

The diagnostics record specifies the files used for audit and error 
logging and specifies the default logging level. The configuration text file 
must contain only one diagnostics record. Table 3-3, "Summary of 
diagnostics Parameters," summarizes the parameters in a diagnostics 
record. 

Summary of diagnostics Parameters 


Specify values for any desired optional fields as described in the 
following list: 

error_file 

Use 5-49 characters to indicate the full path and file 
name of the error log file, which is used to record 
exception and problem messages. The file extension 
must be either .log or .err. 

I f you want to send both error and audit messages to 
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the same file, use the file extension . log and specify 
the same value for this field and for the audit_fiie 
field. 


audit_file 

Use 5-49 characters to indicate the full path and file 
name of the audit log file, which is used to record audit 
messages. The file extension must be either . log or 

. aud. 

If you want to send both error and audit messages to 
the same file, use the file extension . log and specify 
the same value for this field and for the error_fiie 
field. 


audit 


I nclude this field with no value to enable audit 
messages, or do not include this field to disable audit 
messages. Audit messages record normal system 
events. 


exception 

I nclude this field with no value to enable exception 
messages, or do not include this field to disable 
exception messages. Exception messages record 
abnormal events that do not necessarily indicate 
probl ems. 

Problem messages are always enabled. For more 
information about the three types of log messages, see 
Chapter 4, "UsingTN3270 Log Messages." 


rtm_bdy_n 

The four rtm_bdy values specify the boundaries, in 
tenths of seconds, by which host response times on 
TN3270 sessions are classified. If you give TN 3270 
users permission to view RTM data, they can view (for 
each session) a chart of the percentage of host response 
times in each of the time intervals specified by these 
boundaries. For example, if you specify rtm_bdy_l 
through rtm_bdy_4, users can view the percentage of 
responses below boundary 1, between boundaries 1 and 
2, between boundaries 2 and 3, between boundaries 3 
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[diagnostics] 
error_file 
audit_file 
exception 
logged, 

rtm_bdy_l 

rtm_bdy_2 

rtm_bdy_3 

rtm_bdy_4 
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and 4, and above boundary 4. 

Specify the boundaries as decimal numbers, from 
5-1000, representing tenths of seconds. A value of 10 
represents 1 second. The boundaries must not overlap. 
Boundary 4 must be greater than boundary 3, 
boundary 3 must be greater than boundary 2, and 
boundary 2 must be greater than boundary 1. 

Following is an example of a diagnostics record: 

Example of a diagnostics Record 


= /var/opt/tn3270/current.err 
= /var/opt/tn3270/current.aud 

; problem and exception messages are 



r 

but not audit messages 

10 

r 

1 second 

20 

r 

2 seconds 

50 

r 

5 seconds 

100 

r 

10 seconds 
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Overview 

This chapter provides information about how to control the logging and 
format of TN3270 log messages and explains what types of actions you 
can take based on information in the messages. 
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Overview of TN3270 Logging 

TN3270 logs messages for the following event categories: 
Problem event 


An abnormal event that degrades the system in a way 
that is easily perceived by a user. An example is 
abnormal termination of a session. 

TN 3270 always logs these events. You cannot choose to 
disable logging of these events. By default, TN3270 
logs these events to the file sna.err in the 
/var/opt/tn3270 subdirectory. You can specify a 
different file name in the diagnostics configuration 
file record. 


Exception event 

The foil owing are categories of exception events: 

• Abnormal system events that degrade system 
performance but are not immediately perceived by a 
user. An example is a resource shortage. 

• Events that do not degrade system performance but 
may i ndi cate the cause of I ater excepti ons or 
problems. An example is receiving an unexpected 
message from the remote system. 

You can choose to disable logging of these events by not 
including the exception flag in the diagnostics 
configuration file record. By default, TN3270 logs these 
events to the file sna.err in the /var/opt/tn3270 
subdirectory. You can specify a different file name in 
the diagnostics configuration file record. 

Audit event 


A normal system event. An example is starting a 
session. 

You can choose to disable logging of these events by not 
including the audit flag in the diagnostics 
configuration file record. By default, TN3270 logs these 
events to the file sna.aud in the /var/opt/tn3270 


Chapter 4 


47 




Using TN3270 Log Messages 

Overview of TN3270 Logging 


subdirectory. You can specify a different file name in 
the diagnostics configuration file record. 

If you prefer, you can specify that TN 3270 log all messages to the same 
file by specifying the name of that file with the extension . log in both 
the exception and audit fields of the diagnostics configuration file 
record. 

For more information about the diagnostics configuration file record, 
see Chapter 3, "ConfiguringTN3270." 
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Backing Up and Resetting a Log File 

TN3270 provides a backup mechanism to prevent log files from becoming 
too large and consuming disk resources. When a log file reaches 1 
megabyte, TN3270 copies its current contents to a backup file and then 
clears the log file. If error and audit information is logged in one file, a 
maximum of 2 megabytes of log information is stored. If error and audit 
information is logged in separate files, a maximum of 4 megabytes of log 
information is stored. 

The backup file has the file namebak and the same file extension as the 
file it is backing up. The backup file is created in the same directory as 
the audit or error log file from which it is copied. If you need to keep the 
information, rename this file or copy it to a different directory so that it 
is not overwritten the next time the log file reaches 1 megabyte. 


Chapter 4 


49 




Using TN3270 Log Messages 

Format of Log Messages 


Format of Log Messages 

This section explains the information given in the log filefor each 
message. The following exampleshows a typical log message with notes 
on the information shown on each line: 

Example 4-1 Log Message Sample 

12:17:28 GMT 11 Nov 1996 - Timestamp 
3270 Message 0-26, Subcode: 0 
Log category: PROBLEM Cause Type: Config 
System: tnbox 
Process ID: 12345 (tn3270) 


Component, Message #, Subcode 
Log category. Cause type 
System name 
Process ID and name 


There are no sessions configured for 3270 user abc. Message text, including 
parameters 

Cause: The user has tried to start the 3270 emulation Message cause 

program, but no sessions are configured for this user in the 
configuration file. 

Action: If this user is to be permitted to use the 3270 Message action 

emulation program, at least one session must be configured 
for the user. 

Each message contains the foil owing information: 

Timestamp 

The time and date the message was logged. 

Component 

The TN 3270 component that logged the message. The 
value 3270 indicates that theTN3270 emulation 
program logged the message. 

Message number 

An identifier for the message. 

Subcode 
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A unique identifier that indicates the point within 
TN3270 at which the message was logged. This 
subcode is used only by support personnel. 
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Log category 

The event category of the log message. Possible values 
are Problem, Exception, or Audit events. 


Cause type 

A summary of the cause of the message. Possible values 
are: 

Internal 

I nternal error in theTN 3270 software. Report errors of 
this type to your TN 3270 support personnel. 

System limit 

An internal limiting value in theTN3270 software. 

External 

A cause external to TN 3270. 

Resource 

Resource shortage (for example, insufficient memory on 
the H P-UX computer). 

User 

User error (for example, the user has entered invalid 
parameters on theTN3270 emulation program 
command line). 

SNA 

SNA protocol violation by the host system, or 
interoperability problem with the host system's SNA 
implementation. 

Config 

Error in theTN3270 configuration, or mismatch 
between theTN3270 configuration and the host 
system. 

Audit 

A normal event, reported for information only. 


System name 

The name of the computer where the condition that 
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caused the message was detected. 

Process ID and name 

The HP-UX process ID and executable name of the 
process that logged the message. 


Message text 

Text describing the condition being logged. This field 
may include a number of variable parameters relating 
to this particular occurrence of the message. For 
example, a message reporting failure to start a TN 3270 
session may include the TN 3270 user name and the 
session number. 

Message cause 

Additional information about the cause of the condition 
being logged. This field may not be included if the 
message text contains all the required information. 
This field is generally not used when the cause type 
specifies I nternal. 

Message action 

Recommended action as a result of the message. For 
more information, see "Recommended Actions for Log 
Messages". For audit messages, which provide 
accounting and progress information instead of 
reporting error conditions, this field is not included 
because no action is required. 
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Recommended Actions for Log Messages 

The Message action field for a logged message describes the 
recommended action. I n some cases, no action is required. For example, 
an exception message may not indicate an error, but it may provide 
background information that helps to identify the cause of a later 
problem message. 

Common recommended actions include the foil owing: 

• Check theTN3270 configuration, and add or modify resources. 

• Check the H P-UX computer's resources, such as memory or hard disk 
space. 

• Contact support personnel for the host system with which TN3270 is 
communicatingto resolve configuration mismatches between TN3270 
and the host system configuration. 

• Contact the developer of a H LLAPI application if the application is 
making invalid API calls. 

• Report theerror condition to your TN 3270 supplier if the Cause type 
field indicates an internal error in the TN 3270 software. 

The following sections provide more information about some of these 
actions. 

Contacting Support Personnel 

The Message action field may recommend that you contact one of the 
following types of support personnel: 

Support personnel for the remote system 

Support personnel at the host system with which 
TN3270 is communicating. 

Support services 

Support personnel at the company from which you 
bought TN 3270. 
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Sending Log and Trace Files to Support Personnel 

If the recommended action for a message includes sending the log files 
and trace files to support services, provide the error and audit log files 
created when the error occurred. Iftracing was enabled, provide the 
trace files as well. 

If you were runningTN3270 with audit logging or exception logging (or 
both) disabled, attempt to reproduce the problem with all categories of 
logging enabled. If you reproduce the problem, provide the new log files 
that include all event categories. 

Your configuration files may contain information that you do not want to 
make avail able to a third party. If the recommended action asks you to 
send the configuration file to third-party support services, you may want 
to remove some information before sending the file. M odify or blank out 
the parameters instead of removing them completely, and provide a note 
explaining which parameters have been modified when you send thefile. 

Operating System Return Codes 

The return code from an operating system call is sometimes returned in 
the Message text field. The return code may be shown either as a 
symbolic name or as a numeric value. Check numeric values in the 
errno.hfileon the computer where the error occurred to find the 
corresponding symbolic name. The symbolic names are listed in your 
operating system documentation. 
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Overview 

This chapter explains how to use TN 3270 trace facilities to col led 
diagnostics data and how to produce trace output. 
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Overview of TN3270 Tracing 

TN 3270 supports the fol I owi ng types of trad ng: 

HLLAPI tracing 

Traces all the parameters that the HLLAPI application 
supplies to the H LLAPI library and all the parameters 
that the H LLAPI library returns to the application. For 
more information, see "Control ling Tracing of HLLAPI 
Applications". 

TN 3270 M essage trad ng 

T races all the data sent from the host to the TN 3270 
emulation program and from the TN 3270 emulation 
program to the host. This tracing can also include 
TN3270 internal control messages. For more 
i nformati on, see "Control I i ng Traci ng of the TN 3270 
Program". 

The relationship between TN3270 components and the boundaries 
between components at which tracing can be activated is shown in 
Figure 5-1, "Relationship between TN3270 Components and Tracing 
Boundaries." 

Relationship between TN3270 Components and Tracing 
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Boundaries 



] HLLAPI tracing 


] 3270 message tracing 
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C ontrol I i ng T raci ng 

This section describes how you can start and stop tracing, how you 
specify the names of trace files, and how you can control the size of trace 
files. 

Controlling Tracing of theTN3270 Program 

The snamsg environment variable controls tracing theTN3270 program. 
The syntax for snamsg is: 

filel [ : file2 ] 

Specify the foil owing parameters in the snamsg environment variable: 

filel 

N ame of the trace file. 

file2 


Optionally included name of a second trace file. Use a 
colon to separate the two file names. I f you specify two 
trace files, when onefilehas reached the maxi mum size 
(as specified by the snatracesize environment 
variable), trace data is written tothe second file. When 
the second file has reached the maximum size, trace 
data is written again to the first file. 

snamsg tracing is always active if the environment variable is set. 
Tracing cannot be turned on and off whilethe program is running. 

Trace data must always be written to text files. Do not specify the name 
of a device (such as /dev/tty) or a print spooler as a trace filename. If 
you do not specify a full path for the trace file or files, TN3270 uses the 
directory from which you start the application. 

Controlling Tracing of HLLAPI Applications 

The snatrc environment variable and the HLLAPI Set Session 
Parameters function control HLLAPI application tracing. To use the Set 
Session Parameters function, always set the snatrc environment 
variable before starting the application program. 
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Specifying Trace Files for a HLLAPI Application 

The snatrc environment variable specifies one or two files to hold trace 
data and indicates whether to activate tracing when the application 
starts. The syntax for the snatrc environment variable is: 

filel [ : [ file2 ] [ : ] ] 

Specify the foil owing parameters in the snatrc environment variable: 

filel 

N ame of the trace file. 

file2 


Optionally included name of a second trace file. Use a 
colon to separate the two file names. I f you specify two 
trace files, when onefilehas reached the maxi mum size 
(as specified by the snatracesize environment 
variable), trace data is written tothe second file. When 
the second file has reached the maximum size, trace 
data is written again to the first file. 

Final colon (:) 

The final colon indicates that tracing is active as soon 
as the application is started. If tracing is not active 
when the application is started, it can be activated 
fromwithintheapplication usingtheHLLAPI function 
Set Session Parameters. (For more information, see 
"Control ling Tracing from Within a FILL API 
Application".) If you specify only one file name, use two 
colons to make tracing active as soon as the application 
is started. 

If you specify only one file name, the size of the trace file has no limit. If 
you specify two file names, the maximum size of each trace file is 
specified by the snatracesize environment variable. For more 
information, see "Control ling the Amount of Trace Data". Using two files 
extends the trace period and limits the disk space usage to twice the 
value specified in snatracesize. 

Trace data must always be written to text files. Do not specify the name 
of a device (such as /dev/tty) or a print spooler as a trace filename. If 
you do not specify a full path for the trace file or files, TN3270 uses the 
directory from which you start the application. 
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The following examples illustrate the snatracesize environment 
variable: 

filel.trc:file2.trc 

Trace to filei and file2. Tracing is inactive when the H LLAPI 
application is started. 

filea.trc:: 

Trace to one file (f ilea. trc). T racing starts when the H LLAPI 
application is started. 

Controlling Tracing from Within a HLLAPI Application 

TheTRON and troff options of the HLLAPI Set Session 
Parameters function enableyou to trace the specific section of a HLLAPI 
program where a problem is being encountered (without having to trace 
the whole application). Tracing can be activated at the start of this 
section and deactivated at the end of it. Refer to the H P-UX SNAplus2 
3270 & TN3270 HLLAPI Programmers Guide for more information. 

To use this facility, the snatrc environment variable must beset before 
the application program is started. For more information, see 
"Control ling Tracing of HLLAPI Applications". When setting this 
environment variable, set tracing to be active or inactive when the 
HLLAPI application is started and then activate it or deactivate it from 
within the application as required. 

You can disable the tron and troff options by using the snactl 
environment variable. 

Disabling the Application's Control of Tracing 

The snactl environment variable overrides the tron and troff 
options of the HLLAPI Set Session Parameters function SO that the 
application cannot control its own tracing. You can use snactl toforce 
the tracing of an application program that normally turns tracing off for 
some functions, or to prevent tracing for an application program that 
normally uses it. 

If the snactl variable is set before the application program is started, 
any tron and troff tracing control requests from within the 
application program are ignored, although the return code indicates a 
successful completion. If tracing is on, it remains on; if tracing isoff, it 
remains off. 
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To use snactl, set it to any non-blank string. To cancel it, set snactl to 
a blank character. 

Controlling the Amount of Trace Data 

The foil owing environment variables control the amount of data stored in 
trace files: 

SNATRUNC 


Specifies the maximum length in bytes of each entry in 
a trace file. This variable applies both to H LLAPI trace 
files (specified by the snatrc environment variable) 
andtoTN3270 emulation program tracing (specified by 
the snamsg environment variable). 

Set this variable to a decimal number. If a message has 
more characters than this value, the excess characters 
are truncated. For example, setting snatrunc to 70 
limits tracing to 70 bytes of data per entry. By default, 
the length of internal messages is limited to a 
maximum of 256 bytes. 


SNATRACESIZE 


Specifies the maximum size in bytes of each trace file 
when using two files. This value applies both to 
H LLAPI trace files (specified by the snatrc 
environment variable) and toTN3270 emulation 
program trad ng (specified by the snamsg envi ronment 
variable), but only when tracing to two files. If you are 
tracing to one file, the size of the trace file has no limit. 

Set this environment variableto a decimal number. 
When TN 3270 is writi ng a message to one of the trace 
files and the maximum file size is reached, TN3270 
clears the other trace file and continues tracing to that 
file. This ensures that the maximum amount of disk 
space taken up by a pair of user-space trace files is 
approximately twice the value of snatracesize. 

If you do not set snatracesize, the default is 1 
megabyte. To cancel the snatracesize setting and 
return to the default, set snatracesize to a blank 
character. 
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Resetting Trace Files 

The snatrcreset environment variable controls whether a trace file is 
reset when an application first writestoit. Normally, thefileis reset and 
its contents discarded when an application writes its first trace message 
to the file. If you are tracing two or more applications to the same file, or 
if you want to trace two or more runs of the same application to the same 
file, you can prevent the file from being reset by setting the 
snatrcreset environment variable to no. 

If you are tracing to two files, the files continue to be reset as normal 
when the maximum file size is reached, but they will not be reset when 
an application starts tracing for the first time. If you are tracing to one 
file, setting snatrcreset to no means that thefile will never be reset 
automatically. To avoid taking up too much disk space, delete it manually 
from time to time. 

Tocancel the setting of snatrcreset and return to the default setting 
so that thefile is reset when an application first traces to it, set 

SNATRCRESET to YES. 
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Trace File Formats 

This section provides examples and information about how to interpret 
the trace output for the different trace types. 

Common File Information 

The trace data for a single message can occupy more than one line in the 
trace file. Each individual message is preceded by a horizontal line 
indicating the time at which the trace entry was made. The foil owing 
information is common to both TN3270 emulation program tracing and 
HLLAPI tracing: 

• The 5-digit process ID of the component being traced appears at the 
start of each line. The process ID isfollowed by an indicator of the 
type of component being traced (ehll for a HLLAPI application, or 
3270 for the 3270 emulation program). 

• Message data isshown in the foil owing formats in separate columns 
to ensure that a character string in the message data appears as 
readabletext in either the EBCDIC or the ASCI I column according to 
its character set: 

— Hexadecimal 

— Interpreted as EBCDIC 

— Interpreted as ASCII 

File Information for TN3270 Message Tracing 

TN3270 provides the foil owing types of message tracing for theTN3270 
program: 

I nternal 


Traces messages internal toTN3270. These messages 
are used primarily by TN3270 support personnel, who 
may ask you to provide trace files to assist them in 
diagnosing problems with TN3270. 

TCP/IP data 


T races the messages sent over TCP/IP to the host i n 
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the format in which they flow over the network. These 
messages are useful for investigating network 
probl ems. 

FMI data 

Traces data transferred between TN3270 and the host 
in the format in which they are represented inside 
TN3270. These messages can be useful for 
investigating local problems and problems with remote 
systems. 

The start of each trace entry shows the type of message bei ng traced and 
a decoded version of some of the header information. The header 
information and message data is then traced. 

The header information in trace messages uses the foil owing 
abbreviations: 

Abbreviations Used in Trace Message Headers 


+RSP 

Positive response 

-RSP 

Negative response 

BBI 

Begin bracket indicator 

BCI 

Begin chain indicator 

CEB 

Conditional end bracket 

DAF 

Destination address field 

DR1,DR2 

Definite response 1 and 2 indicators 

EBI 

End bracket indicator 

ECI 

End chain indicator 

ERI 

Exception response indicator 

OAF 

Origin address field 

ODAI 

OAF/DAF indicator 

RH 

Request header or response header 

RU 

Request unit or response unit 
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Abbreviations Used in Trace Message Headers 

sc Session control 

th Transmission header 


File Information for HLLAPI Tracing 

The foil owing parameters for each HLLAPI function are traced when the 
function is issued and again when it returns. 

fun c_number 

This parameter is shown in parentheses after the name 
of the function. 

data_length and ps_position/return code 

These parameters are always shown following 

f un c_n umber. 

data_string 

This parameter is traced only if it is used by this 
function. 
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Overview 

This chapter describes how to define the required or recommended 
functions in the terminfo database. 
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Defining Functions in terminfo 

Toallow HP-UX terminalsto use the screen interface of theTN3270 
program, define the foil owing required or recommended functions in the 
terminfo database. To alter the terminfo database, use the tic and 
infocmp programs provided with your HP-UX operating system. Refer to 
the termi nfo man page for your operati ng system for more i nformation 
about terminfo database, and the tic and infocmp programs. The 
termcap names are shown in the terminfo entries that refer to them. 

Required functions 

Terminals without the following functions cannot be 
used with theTN3270 program, unless theTN3270 
program is running in the background. They can, 
however, be used for other TN3270 functions such as 
running H LLAPI application programs or creating 
configuration files. 

Screen size 

The screen size defined in terminfo (the cols and 
rows entries) must be at least 80 columns by 24 rows. 

Cursor addressability 

Menus and dialog boxes cannot be drawn without this 
function. 

FI function key: kfl 

This key is used to invoke the online help facility. 

Up and Down arrow Keys: kcuul and kcudl 

These keys are used to move within list boxes and to 
select buttons from radio groups. 

Recommended functions 

The foilowing functions make the screen interface 
easier to use, but the interface can be used without 
them. 

Alternate character mode: acsc, enacs, smacs, rmacs 
Used todraw the menus and dialog boxes. If the 


Appendix A 


69 




Required and Recommended Functions in the terminfo Database 

Defining Functions in terminfo 


HP-UX terminal does not support drawing menus and 
dialog boxes, it can still use the menu interface, but the 
menus and dialog boxes will be drawn with characters 
such as - and + instead of solid lines. 

TheTN3270 program with the international option 
uses the I SO 8859 character set instead of the PC 
character set. In this case, whether you can display the 
box drawing characters depends on your version of 
HP-UX and its curses library. You may be able to use 
them by modifying the acsc mapping, or you may have 
to remove the acsc mappi ng and use the - and + 
characters. 

F2. .. F12 function keys: kf2 . . . kfl2 

Used in TN3270 emulation to represent the 3270 keys 
PF2 to PF12. Some of these keys are also used as 
accelerators in the menu interface to provide a 
"short-cut" to certain dialogs or functions. If you do not 
have these keys, you can remap the 3270 keys to 
different keystrokes. The accelerator keys cannot be 
remapped, but it is possible to reach the same dialogs 
or functions by using the main screen menus. 

Left and Right arrow keys: kcubl and kcufl 

Used for moving within edit boxes and for selecting 
buttons from radio groups. I f you do not have these 
keys, you can replace text in edit boxes instead of 
modifying it, and you can use the Up and Down arrow 
keys or accelerator keys to select buttons from radio 
groups. 

PageUp: kpp or ka3 and PageDown: knp or kc3 

Used to move quickly within a listbox. The Up and 
Down arrow keys can be used instead, but are slower. 

E ither of the termcap names can be used. 

Home: kal or khome and End: kcl 

Used to move quickly to the first or last entry in a 
listbox. The Up and Down arrow keys or PageUp and 
PageDown can be used instead, but are slower. 

Backtab: kcbt 
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Used for moving backwards through the sequence of 
items in a dialog box. If Backtab is not available, the 
keystroke Ctrl+B can be used instead. (These 
keystrokes are equivalent only in the menu interface.) 

I n TN3270 emulation, the default key mapping for the 
3270 BACKTAB key is Backtab; remap this to Ctrl+B or 
any other suitable keystroke if you do not have the 
Backtab key. 

Insert, Delete, and Backspace: kichl, kdchl, and kbs 

Insert and Delete are used in theTN3270 emulation 
program as defaults for the 3270 IN SE RT and 
DELETE keys. If Insert and Delete arenot available, the 
3270 keys can be remapped to different keystrokes. 
Delete and Backspace can be useful for modifying 
information in an edit box. (On some terminal types, 
such as the Wyse 60, Backspace is interpreted as a Left 
arrow key.) 

Color support: colors, pairs, setb, setf 

The TN 3270 menu interface can be run without color 
support, but it will use color if your terminal supports 
it. This applies particularly when communicating with 
host TN3270 programs that support color. 

Attribute support: blink, bold, dim, rev, smul, rmul, 
sgrO 

The TN 3270 display screen can be run without 
attribute support, but if your terminal provides 
attributesupport, attributesupport displays underline, 
reverse and blinking characters sent by the host. 

Blinking characters do not display as blinking on Motif 
displays. 

Access to termi nal's status I i ne: hs, fsl, tsl 

If your terminal's hardware supports a status line to 
which user programs can write, you can customize 
TN 3270 sessions to write the 3270 status I i ne to the 
terminal's status line. If this feature is not available, 
theTN3270 emulation program usesthelast line of the 
screen to display the status line. Depending on the 
TN3270 screen model and the terminal's screen size, 
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this may mean that the last line of the screen is shared 
between theTN3270 display and the status line. 

TheTN3270 program's default keyboard mapping (the mapping between 
keystrokes on the HP-UX terminal and the 3270 keys they represent) 
assumes that the H P-UX terminal's keyboard has all the keys included 
in both the Required and Recommended lists. However, you can remap a 
3270 key to a different keystroke if your H P-UX terminal does not have 
the same key. Refer to the HP-UX TN3270 Users Guide for more 
information. 

I nclude in the terminfo database any additional keys on the terminal's 
keyboard if you want to use them i n the TN 3270 program to represent 
3270 keys. For example, if you have the function keys F13-F24, map the 
3270 keys PF13- PF 24 to these keys. 

I n some cases you may need to alter the terminfo database to i ncl ude 
the functions shown. For example, if the keyboard has the PageUp and 
PageDown keys, but its terminfo entry does not include them, edit the 
terminfo entry to i ncl ude them. 

To use the Motif menu interface, the H P-UX computer requires (Xll 
Release5 and Motif Version 1.2, and an X display terminal. All of the 
required or recommended keys are generally available with this 
hardware and software. 

The required and recommended keys in this section (such as function 
keys and cursor keys) are required or recommended for the Motif 
interface as well as the character-based interface. The other functions 
(such as screen size and alternate character mode) do not apply to the 
Motif interface. 


72 


Appendix A 




Using Shared Memory and 
Semaphores 


This appendix describes how to define the amount of shared memory and 
semaphores required by TN3270on the HP-UX computer. 
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Tuning System Parameters 

N ormal ly, the default val ues for these parameters are suitable for typical 
TN 3270 configurati ons. I n some cases, it may be necessary to tune some 
of these parameters. Tuning should only be done once TN 3270 has been 
successfully installed and started using the defaults. The parameters 
should be set to large enough values to accommodate both theTN3270 
requirements and the requirements of any other programs on the 
system. 

I f you need to change any of these val ues, refer to your HP-UX 
documentation for information about how to set them. Following are the 
tuning parameters and their recommended values: 


SHMMNI 

1 + (number of concurrent copies of the TN 3270 
emulation program) +(total number of sessions 
configured for HLLAPI) 

SEMMNI 

(2 x number of concurrent copies of theTN3270 
emulation) + (total number of sessions configured for 
HLLAPI) 

SEMMNS 

(2 x number of concurrent copies of the TN 3270 
emulation program) +(2 x total number of sessions 
configured for HLLAPI) 

SEMMAP 

H alf the val ue of semmns 

SEMMNU 

(2 x number of concurrent copies of the TN 3270 
emulation program) + (total number of sessions 
configured for HLLAPI) 

SHMSEG 

2 + (maximum number of sessions configured for 
HLLAPI for a single user) 


NOTE You can run morethan oneTN3270 emulation program at a time using 

different HLLAPI session identifiers, and therefore, can have more 
HLLAPI sessions configured than a single emulation program can 
support. These parameters must be large enough to support all of these 
sessions, even if you do not access all of them from a single H LLAPI 
application. 
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Overview 

This appendix explains how to migrate from an earlier version of 
TN3270 to the current version. 
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Summary of Migrating from TN3270 Release 4 
to TN3270 Release 6 

The following summary helps you determine the migration steps that 
you need to take. Depending on the TN 3270 functions that you use, you 
may not need to perform all of the steps. To migrate from TN 3270 
Rel ease 4 to TN 3270 Rel ease 6, perform the fol I owi ng steps: 

Step 1. Use the configuration migration program tnmigrate to modify the 

runningTN3270 configuration file /etc/opt/tn3270/com.cfg and any 
other TN3270 configuration files that you use. Migrating the 
configuration files enables you to use the new log message types in 
TN 3270 Rel ease 6. 

To learn how to run the configuration migration program and to 
understand the changes it makes to the configuration file, see "Modifying 
Configuration Files". 

Step 2. Because the tnmigrate program changes the existing configuration text 
files, run thetncfgtcp program to convert them toTN3270 Release6 
binary configuration files. For more information about the tncfgtcp 
program, see "Creating a Binary Configuration File". 

Step 3. Review any tools or processes that you have developed for use with 

TN3270 log or trace files to determine if they need modification to reflect 
changes in theTN3270 log fileformat. To understand how the log file 
format has changed from Release 4 to Release 6, see "Log Messages and 
Log File Format", and 'Trace File Format". 

Modifying Configuration Files 

TN3270 Release 6 classifies log messages into three categories (audit, 
exception, and problem) and allows you to specify in your configuration 
file whether audit or exception (or both) logs are recorded. For more 
information about thesethree log message types, seeChapter 4, "Using 
TN3270 Log Messages."TN3270 Release4 classifies log messages by 
level (6, 8,10,12, and 16) and allows you tospecify the minimum level to 
record. 

Before using an existing Release 4 configuration file with Release 6, you 
need to modify it to take account of this change. TN3270 provides a 
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migration program to make the necessary modifications to the 
configuration file. For more information about the configuration file 
format, see Chapter 3, "ConfiguringTN3270." 

Running the Configuration Migration Program 

Torunthe migration utility, use the foil owing command: 

tnmigrate [-c ] oldfilename newfilename 

The command contains the foil owing parameters: 

oldfilename 

Name of the Release 4 text configuration file. Specify a 
full path if it is not in the current directory. The 
configuration migration program adds the filename 
extension .txt if you do not specify it. 

newfilename 

Name of the Release 6 text configuration file to be 
created. The configuration migration program creates 
the file in the current directory if no path is specified 
and adds the filename extension .txt if no filename 
extension is specified. 

-c 


Specifies that the program should generate the Release 
6 binary configuration file in addition to the text file. 
The file is given the same name as the output text file 
but with the extension .cfg instead of .txt. If you do 
not use this option, you must use the tncfgtcp 
program to create the binary configuration file. For 
more information about the text and binary 
configuration files and about converting between these 
two file formats, see Chapter 3, "ConfiguringTN3270." 

Changes Made by the Configuration Migration Program 

The only record in the configuration fiIe that the configuration migration 
program modifies is the diagnostics record. The configuration 
migration program modifies this record to remove the audit_ievei field 
and to add the new audit and exception fields, if appropriate. The 
settings of audit and exception are based on the value of audit_ievei, 
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Table C-l 


as follows: 


audit Ievel(Release 

4) 

Release 6 field 

(omitted) 

exception 

10 

exception 

8 

audit, exception 

6 

audit, exception 


For more information about the audit and exception fields, seeChapter 

4, "UsingTN3270 Log Messages." 

Log Messages and Log File Format 

The following are changes in error and audit logging for Release 6: 

• The format of log message files is changed so that the header 
information for each message is now more easily readable. The files 
are still ASCI I text files that can be viewed using a standard ASCI I 
text editor. 

• All information related to a log message, including cause and action, 
is included in the log file. Chapter 4, "UsingTN3270 Log Messages," 
explains how to interpret the information in the file (but no longer 
includes a listing of the cause and action information for each 
message). 

• The log message levels used in Release 4 (16, 12, 10, 8, 6) have been 
replaced by three log message types (Problem, Exception, and Audit). 

• Many of the messages used in Release 4 have been discontinued and 
replaced by new messages. I n addition, message numbers have been 
reassigned so that each component has a well-defined range of 
numbers. Therefore, do not search Release 6 log message files for a 
particular message that was used in Release 4 (either by searching 
for the message number or by searching for specific message text). 

For more information about TN3270 log messages, see Chapter 4, 
"UsingTN3270 Log Messages." 
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Trace File Format 

The format of trace files has changed slightly. I n addition to the 
hexadecimal listing, message data is now interpreted both as EBCDIC 
and as ASCI I in two separate columns rather than being interpreted 
character-by-character as either ASCI I or EBCDIC. 
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